Displays an alert box with a stop icon and/or plays an alert sound.

DialogItemIndex StopAlert (
    SInt16 alertID, 
    ModalFilterUPP modalFilter
);

alertID

The resource ID of an alert resource and extended alert resource. The resource ID of both types of resources must be identical. If the alert resource is missing, the Dialog Manager returns to your application without creating the requested alert. See ‘alrx’ for a description of the extended alert resource.

modalFilter

A universal procedure pointer for a filter function that responds to events not handled by the ModalDialog function. If you set this parameter to null, the Dialog Manager uses the standard event filter function.

function result

If no stop alert box is to be drawn at the current alert stage, StopAlert returns –1; otherwise, it creates and displays the alert box and returns the item number of the control selected by the user; see “Alert Button Constants”.0

DISCUSSION

The StopAlert function displays an alert box with a stop icon in its upper-left corner or, if appropriate for the alert stage, plays an alert sound instead of or in addition to displaying the alert box.

The StopAlert function is the same as the Alert function except that, before drawing the items in the alert box, StopAlert draws the stop icon in the upper-left corner. The stop icon has resource ID 0, which you can also specify with the constant stopIcon . By default, the Dialog Manager uses the standard stop icon from the System file. You can change this icon by providing your own 'ICON' resource with resource ID 0.

Use a stop alert to inform the user that a problem or situation is so serious that the action cannot be completed. Stop alerts typically have only a single button (OK), because all the user can do is acknowledge that the action cannot be completed.

Your application should never draw its own default rings or alert icons. Prior to Mac OS 8, the StopAlert function would only redraw the alert icon and default button ring once and never redraw them on an update event. However, when Appearance is available, alert icons and default rings do redraw when you call StopAlert.

See also the functions NoteAlert and CautionAlert.

VERSION NOTES

This function was changed with Appearance Manager 1.0 to support the extended alert ('alrx') resource.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.

© 2000 Apple Computer, Inc. — (Last Updated 4/14/2000)